feat: CalendarPreview range selection - #897

PR 4 of 7. `selection='range'` on the root, `field="start" | "end"` on
`.Input`, and the from/to machine that ties them together.

BREAKING CHANGE: a range emits only once it is complete. `onSelect` used
to fire on every step with a partial `{ from?, to? }`, and the docs told
consumers to gate on `range.to`. `onValueChange` now fires with both
edges or not at all, `to` stops being nullable, and the gate-on-range.to
idiom retires. Anyone reading the first-click event loses it. No type
error will find this: the old partial satisfies the new shape whenever
`to` happened to be set, so the failure is a callback that stops firing
rather than one that stops compiling.

The half-built range stays internal. It is on the root context so the
grid can draw the track between endpoints, and it is never emitted. The
restart case leaves the consumer's value at the previous complete range
until the new one completes; Escape or closing drops the draft.

The machine is the shipped one, branch for branch: an empty range takes
the first click as `from` and moves focus to the end field; a later
second click completes and closes; an earlier one becomes the new
`from`; a click on a complete range restarts.

Completing writes to open state, which the grid must not do directly, so
it routes through the root's `setOpen` — a consumer controlling `open`
keeps it open and only sees the request.

`lock` is replaced by `readOnly` on one `.Input`. The endpoint registers
itself, because `readOnly` is the input's prop and the grid is the thing
that has to refuse the write. A read-only endpoint with no value makes
the range unsatisfiable — the free endpoint sets, nothing ever completes
— so it needs a value; the docs say so.

Selection arms are discriminated on `selection`, so a single-day
consumer keeps a `Date | null` callback rather than both arms widening
to a union. The implementation stays shared, with one cast at the seam.

Range styling from the frames: endpoints accent-filled and pill-rounded
on their outer edges, the days between on one continuous band rather
than three cell backgrounds. react-day-picker marks every day of a range
`selected`, so the days on the track needed the single-day white text
undone — caught by rendering it, not by reading the CSS.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Completing a range closes the popover, the browser hands focus back to
the trigger, and the focus handler opened it again — the same shape as
the Escape reopen, but the auto-close reason was not in the blocked set
so the guard let it through. `closePress` joins `escapeKey` and
`triggerPress` there.

Emitting `itemPress` was also wrong: it is not in the popover's reason
union, so the close was carrying a reason Base UI's own type says cannot
occur. `closePress` is in the union and is what this is.

jsdom passed throughout, because it does not restore focus to the
trigger the way a browser does. Found by driving real Chrome over CDP.
The regression test asserts the guard rather than the symptom, since the
symptom is not reproducible in jsdom.

Real browser, trusted input, after the fix:

  10 after 2nd click emit:  10-20
  10 auto-closed:           true
  10 range open log:        true:trigger-press,false:close-press

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…eview-rangepicker

Brings the datepicker fixes onto the range branch. Five files conflicted, all
of them where the range work and the incoming rename refactor had touched the
same lines.

- context: kept the CalendarPreviewScale / CalendarPreviewScaleValue rename
  alongside the new range fields. The old Scale / ScaleValue names on our side
  of the hunk were already dead — the imports had auto-merged to the new ones.
- input: kept both new props (field, errorMessages) and took the data-invalid
  fix, but held our value={text ?? committedText}. The incoming
  value={draft ?? ...} would now read the range draft from context rather than
  the input's own text, since the range work renamed that local to text.
- grid: kept handleSelect delegating to the root's selectDay, which already
  owns both the clearable toggle-off and the readOnly / disabled guard, and
  combined the incoming GridRootContext wrapper with the range arm.
- root: the month default needed both sides — valueProp read before
  defaultValue, unwrapped through monthAnchor so a range anchors on its start.
  Took the full setValue dependency list; ours had dropped timeZone, readOnly
  and disabled while the body still read them.
- docs: both sides' new sections, with range selection ordered first so the
  Examples subsections stay together ahead of the top-level ones.

Two breaks the merge itself introduced, fixed here rather than left for the
next build: readOnly was left unbound in the grid, dropped from the context
destructure while the incoming data-readonly on base merged in cleanly, and
monthAnchor / reset stopped typechecking once value widened to include a range.

Widening the value to a range left the parts that consume it still assuming a
Date, which TypeScript could not catch: the context is generic with a
`Date | null` default and the provider casts through `unknown`, so each part
believed it held a day and threw at runtime instead.

- `.Reset` called `dayKey` on the range object and threw on render. It is the
  default composition, `.Days` to `.Header` to `.Reset`, so a range calendar
  with a `defaultDate` did not render at all. A single-day default cannot
  describe a range, so the part now stands down at range selection; a `null`
  default still shows, because clearing means the same thing either way.
- A childless `.Trigger` handed the range to `formatValue`, reaching
  `parseKey(undefined)`. It now labels itself with both endpoints.
- Typing into the end field restarted the range from that day, silently
  rewriting the start and emitting nothing. Typed dates go through a new
  `setEndpoint`, which writes the field that was typed into: a click means
  "the next endpoint", but typing into a field means that field.
- `reset()` wrote a bare Date into a range value, reaching a range consumer's
  callback with the wrong shape. It stands down at range selection too.
- `useCalendar().setValue(null)` passed the range as the `occasion`, which is
  always one day, and threw in `dayKey`. A range now reports the day it starts
  on, and `UseCalendarReturn.value` admits it can hold a range rather than
  claiming `Date | null` while already carrying one.

Eight cases added to range.test.tsx, each verified against the broken code
first: both render crashes, both edit directions, the crossed endpoint, the
read-only endpoint, and the null-default reset.

`defaultDate` sat in the shared props as `Date | null`, so it could not
describe a range and `.Reset` had nothing to restore at range selection. It
moves into the two selection arms instead, taking a day for single and a range
for range, which is how `value`, `defaultValue` and `onValueChange` already
work. No new prop: the same one now follows `selection`.

`reset()` restores whichever shape it was given, reporting the range's start as
the `occasion`, which is one day whatever the value is. It no longer stands
down at range selection, and the shape guard that kept it from writing a bare
Date into a range value is gone because the type now prevents that outright.

`.Reset` compares by shape as well as by day. A day and a range are never the
same default, and both edges have to match before the button counts as
restored — a shared start with a different end still has something to restore.

The Reset docs claimed the button disappears once there is nothing left to
restore, which contradicted both the implementation and the part's own
description a few sections above. It stays mounted and goes disabled, for the
reasons the component already documents: unmounting the focused element
strands a keyboard user, and dropping a child from the header shifts both nav
buttons sideways every time the value crosses the default.

Three demo tabs: a range reset under Reset, a single-day one on the picker, and
one on the range example. All render a single month, because `.Days` only
draws a `.Header` below two and `.Reset` lives inside it.

…rrel

The component barrel exported these; the root one had never had them copied
across, so a consumer could pass `onValidityChange` or `onOpenChange` a handler
but could not name the type of its argument.

Six move up: the input's props, validity and invalid-reason types, the trigger
and content props, and the open-change details. The two barrels now match
exactly, so the gap closes rather than shrinking by whichever names came up.

Types only. Nothing about runtime, the docs site or the rendered prop tables
changes — those are generated from the docs' own props.ts, not from here.